Round-2 audit fixes: strict v2 position_id (A-m5), physical-size read errors (A-m6), exact unit conversion (B-m7) - #142

Three fixes from the cross-brick round-2 audit (3 November 2026). An independent review follows, so please do not merge yet.

Summary (by module)

A-m5: position_id is required in v2 manifests

• New module manifest_fields.py (pure). It holds recorded_position_id(value, relative_path, strict=) and the roles check, which moved here from manifest.py.
• In version 2, the reader (_file_entry) and the writer (_file_dict) refuse three cases, and each message names the entry and the identifier its name gives:
  • a missing or null position_id;
  • a value that is not text;
  • any value other than position_id(relative_path) (D85: the image name without its extension, never parsed).
• Version 1 manifests are read as before.
• run_inputs._fov no longer turns a missing id into "". It raises RunInputsError instead.
• manifest.py goes from 598 to 592 lines.
• rc4 compatibility: tests/data/rc4_run_manifest.json was written by the v0.4.0rc4 code (git archive v0.4.0rc4, run through tests/data/make_rc4_manifest.py). The test reads it. Its names cover .tif, .TIFF, .ome.tif, a name with dots, a space and .ome.zarr.
• position_id was always filled by the writers: every rc tag (rc1 to rc4) sets it through file_entry_with, and image_names.py has not changed since rc1.

A-m6: TIFF calibration read errors (verified first)

• What was wrong before the fix:
  • a missing, truncated or non-TIFF file gave all-None sizes with no reason;
  • a programming error inside the reader was swallowed in the same way;
  • when tifffile cannot read an XResolution tag (value offset beyond the end of the file, or an unknown type), it drops the tag and only logs. X then read as uncalibrated with no reason, while Y stayed 0.5.
• New module tiff_size_values.py (io) with two documented exception sets:
  • TIFF_OPEN_ERRORS = (OSError, ValueError, TypeError, struct.error) guards only the tifffile.TiffFile(path) call. Fuzzing tifffile 2026.10.15 showed that it raises TypeError and struct.error on some damaged IFDs, as well as TiffFileError.
  • METADATA_READ_ERRORS = (OSError, struct.error, TiffFileError) covers reading the metadata of an open file.
• Both give all-None sizes with the reason in PhysicalSizes.invalid, which produces the invalid_physical_calibration warning.
• A file with no metadata is still simply uncalibrated.
• Any other exception is raised. A non-path argument is a TypeError, because tifffile raises ValueError for one.
• A lone ImageJ resolution tag now names the missing one.
• The value helpers moved to the new module, with full annotations (5 fewer noqa: ANN). physical_sizes.py goes from 600 to 566 lines, and physical_sizes.read_physical_sizes is still importable (MorphoRelate imports it).

B-m7: exact unit conversion

• length_units._MICROMETERS is now a table of (multiplier, divisor) integers.
• Units smaller than µm divide by the integer inverse factor; larger units multiply by the integer factor. 9 nm now gives 0.009; before it gave 0.009000000000000001.
• This repository's own non_square_pixels check uses exact equality too, so X in nm with Y in µm for the same size no longer warns. There is a test for it.

Decisions

• A-m6 changes inspect_tiff only for tag-read errors. These now become the invalid_physical_calibration warning instead of an unreadable file. A file that cannot be opened is still unreadable_tiff in the folder check.
• B-m7 follows the requested divide/multiply rule, which gives these guarantees:
  • to_micrometers(x, "nm") == x / 1000 for every value tested;
  • a value that is exact in binary gives the double nearest its exact length in µm, the same in every unit where it is exact, and equal to that length written in µm ("0.009").

Notes for review

• Remaining 1-ULP gap (B-m7). A value that is not exact in binary (for example 0.1 nm or 108.33 nm) can still differ by 1 ULP from the same length written in µm. In a seeded sample of decimals with up to 6 places, this happened for about 21% of nm values and 11% of mm values.
  • Removing the gap would take a decimal conversion through repr. That would break the requested == x/1000 property, so I did not do it.
  • The 0.1% rule (same_pixel_size) is not affected. Exact-equality tests in other bricks are affected only for such values.
• Existing tests changed:
  • test_run.py: a test deleted position_id from a v2 manifest and expected every row to be reused. That manifest is now refused (every image is read again). The table case stays in test_run.py; the manifest case moved to test_manifest_position_id.py.
  • The test helper in test_manifest.py now fills position_id.
  • The numpy-scalar test in test_audit_run_inputs.py now expects / 1000.
• Golden outputs: no fixture or golden output depends on the old conversion. Manifests record each size in its own unit, and the v2 CSV fixtures contain no µm values. The full suite passes unchanged apart from the tests listed above.
• tools/code_rules.py is unchanged (SHA prefix cc04a420). The baseline only shrank: noqa ANN from 51 to 46, tests/test_run.py from 862 to 860 lines.
• No new code uses noqa. ruff check --ignore-noqa passes on every new file.

Tests

• ruff check .: all checks passed. ruff format --check .: 221 files already formatted.
• python tools/check.py --rules: passed.
• pytest with .[dev,notebook,zarr] (Python 3.13, Linux): 2138 passed, 4 skipped. The skips are expected: 3 case-sensitive file system checks and 1 file-permission check, because the tests run as root.
• New tests:
  • test_exact_unit_conversion.py (11)
  • test_manifest_position_id.py (15)
  • test_tiff_size_read_errors.py (19)
• Without the fixes, 10 of the 14 original A-m5 tests, 17 of the 19 A-m6 tests and 6 of the 10 original B-m7 tests failed.
• CI on e4b73b6: all 7 jobs passed (lint, and Ubuntu, Windows and macOS on Python 3.11 and 3.13).

🤖 Generated with Claude Code

https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc